v1.2接入stripe 支付需求描述

一、支付规则

● 所有区域详情（报告）（按邮编）需要购买，购买后获取固定时间的访问权限（如 3 个月）

● 有效更新时间段内可随时查看最新的数据区域详情（报告）和分析，所有邮编访问的区域详情（报告）都是最新版数据；

●  超过有效期则不能继续查看区域详情（报告）内容，也不可以可以查看历史版本区域详情（报告）

● 有效期规则：按照解锁当日+指定时间自然日 23:59:59过期

○ 如 1.28 解锁，有效期 90 天， 90 天后的 23:59:59，不包括解锁当天

○ 这里的自然日是 local time

2.1 功能清单

RR v1.2支付流程功能清单

二、 Snapshot快照页

1.  界面交互

2.  功能点描述

● 用户搜索后展示快照页，需要根据用户是否登录/是否购买区域详情（报告）的情况来展示对应的情况，已下是用户对应的情况说明：

a.  未登录：用户为非登录态：需要先登录

b.  已登录，未购买，无次数：用户已登录&当前所查看的区域详情（报告）（以邮编作为区分）未购买，也没有可用的次数

c.  已登录，未购买，有次数：用户已登录&当前所查看的区域详情（报告）（以邮编作为区分）未购买，还有之前购买的次数可以直接兑换一份区域详情（报告）

d.  已登录，已购买且在有效期内：用户登录&用户已经购买当前邮编所属区域详情（报告）（包括使用免费额度兑换&支付购买）

e.  已登录，已购买，但未在有效更新期内：用户登录&用户购买过当前邮编所属区域详情（报告）（包括使用免费额度兑换&支付购买），但当前时间已不在有效更新期内——需要重新购买

● 快照页根据用户的情况模块和交互处理

●  以上所有跳转按钮将首先检查用户是否已登录（同已有的 snapshot 一致）

○  如果未登录，它们将触发登录流程。登录后继续完成上一个操作，不需要用户重复操作（如点击购买，如未登录先登录，登录成功后已经进入支付流程，不需要再次点击支付按钮）

○ 如果已登录，则 参考以上交互说明进入后续的支付/解锁流程，具体可见第三部分。

○ 完成支付/解锁后，点击进入区域详情（报告）页时，同步检查该邮编是否已有完整区域详情（报告），以及该区域详情（报告）内所有维度的数据是否符合时效性要求，触发相关区域详情（报告）生成流程。

○ 在有效期内，通过 snapshot 页以及支付流程中前往区域详情（报告）页都是最新的数据内容版本；若不在有效期内，通过 snapshot 页需要再次购买才能进入邮编详情页

●  增加 Sample 入口，点击后打开对应的样本区域详情页

○ 样本页固定展示提示内容：Sample insights are current as of 1 January 2026. To access the latest insights and real-time updates, please unlock your access.

●  移除限时免费标签

● 收藏功能 Save

○ 用户进入快照页，需要展示出当前邮编区域的收藏状态

■ 点击 Save for later，若当前用户未登录，则先进入登录流程，登录成功后完成收藏

■ 已经登录，点击 Save for later, 收藏成功后弹出 toast 提示：

■ 点击 My Areas可以打开对应页面

■ 收藏成功后，变成已收藏状态

■ 需要进入快照时展示区分已收藏/未收藏状态

三、  获取/购买区域详情（报告）流程

● 有剩余次数，优先用剩余次数解锁

● 无有效的剩余次数，再进入购买流程

● 首次不再免费，提供了 sample area insights 可供查看

● 解锁区域详情过期后，同样按照以上逻辑进行校验判断

1.  购买区域详情（报告）流程：

● 用户未登录，先走登录流程

● 用户登录后，检测用户是否购买，未购买，点击操作按钮，打开定价页 Pricing👇

定价页 Pricing

1. 用户故事 (User Story)

● 作为一个正在看房的购房者，我想要选择最符合我搜索范围的付费套餐，以便于获取特定区域（邮编）的深度分析区域详情（报告），并享受多购优惠。

2. 业务流程/逻辑 (Business Process / Logic)

Code snippet

graph TD
    A[输入邮编并点击搜索] --> B{系统检测邮编状态}
    B -- 未解锁 --> C[进入套餐选择页]
    C --> D[选择套餐: Single/3-Pack/5-Pack]
    D --> E[跳转第三方支付网关 Stripe/Apple Pay]
    E -- 支付成功 --> F[自动解锁当前搜索邮编]
    F --> G[剩余点数记入账户/跳转区域详情（报告）页]
    E -- 支付失败 --> H[停留支付页并报错提示]

3.  详细规格：页面、交互与规则 (Detailed Specs: UI, Interactions & Rules)

● 从快照页进入：

○ [当前解锁提示]： 页面顶部显著位置需加粗显示当前即将解锁的邮编（如：NW1 6XE），增强用户的购买目标感。

■ 仅在用户通过快照页进入定价页后购买展示邮编，若通过top up unlocks 充值余额和价格菜单进入，则不展示邮编，并且不在购买成功后自动解锁对应邮编的 Area Insights

○ [套餐卡片交互]： * 高亮逻辑： 默认高亮“3-Postcode Pack”（Most Popular）。鼠标悬停或点击其他卡片时，边框颜色及按钮颜色需产生视觉反馈。

■ 价值锚点： 每个套餐需计算“单价（Per area）”并展示，同时计算并展示相比单买的省钱百分比（如 Save 33%）。

○ [支付按钮]： 点击后应进入加载状态（Loading），防止用户重复点击。

● 从菜单或 transactions 页充值次数入口进入：

○ 检查用户是否登录，若未登录，先进入登录流程，登录成功后返回并继续支付流程

○ 用户完成登录，则按照用户所选的套餐进入支付页

● 规则与异常：

○ 规则： 套餐为一次性支付（One-time payment），无自动续费。

○ 异常： 若第三方支付网关回调超时，页面应展示“支付确认中，请勿关闭窗口Verifying Payment...”，并每 3 秒轮询一次支付状态，最多 5 次。

○ 需要注意不要出现重复支付的情况

● 选择一个定价模式后进入托管支付页面checkout👇

○ 页面信息相关配置信息待确认

● 支付完成后：

○ 用户通过快照页进入，支付成功后，自动解锁用户关联的邮编，并在支付成功后跳转到对应的邮编详情页，在页面顶部展示 banner 提示；后续再次进入或者点击关闭都不再展示。

■ 支付回调地址都要加上解锁状态确认中的 loading 状态（文案待补充）

■ 如果是直接购买单位区域详情（报告），提示内容：

■ 如果是购买的套餐包，提示内容如下，点击 My Areas 可进入对应的页面

● x 为当次购买剩余可用于解锁的次数

● 如果是重复购买套餐包，第二次支付因为同一份 Area Insights 重复解锁失败，所以会获得所购买的次数，提示内容如下👇

○ 点击 My Areas 可进入对应的页面

○ x 为当次购买剩余可用于解锁的次数

○ 若 AI 还在生成中，已有的 AI 生成中提示优先级低于购买成功提示

● 用户通过定价页/订单页充值进入，支付成功后进入 transactions 页面，并刷新新充值的次数

○ 支付回调地址都要加上解锁状态确认中的 loading 状态（文案待补充）

● 异常情况：若中断支付，或者返回上一页面，需要检测支付状态，展示最新的支付状态

○ 未拿到支付结果前：所有跳转按钮置灰不可点击

○ 拿到支付成功的结果：快照页变成可以前往区域详情（报告）的状态（已登录&已购买），并在页面中展示相关 toast提示

○ 拿到支付取消的状态：用户在支付托管页面，主动点击了“取消”或“返回”链接（未完成支付），或者直接按了浏览器的“返回”按钮。

■ toast 提示：Purchase Cancelled. You can try again anytime.

■  3s 后toast 提示消失

■ 用户在此情况下，可以重新点击按钮，重新进入支付流程

○ 获取到支付异常/失败的状态：用户进行了支付，但是因为卡被拒绝（例如：余额不足、CVC 错误、银行风控）等原因，支付托管页面显示了错误，然后将用户重定向回我们的快照页

■ toast 提示：Your payment didn't go through. Please try again or use a different card."

■  3s 后toast 提示消失

■ 用户在此情况下，可以重新点击按钮，重新进入支付流程

2.  直接用剩余次数解锁流程：

● 用户未登录，先走登录流程

● 用户登录后，检测用户是否购买，未购买，点击右上角按钮，打开二次确认弹窗👇

○ 点击弹窗中的“❌” 或”cancel“关闭弹窗，不可

○ 点击“Get Full Access”打开定价页面

○ 选择一个定价模式后进入 checkout

● 点击弹窗中的“❌”和“Cancel”都是关闭弹窗，不扣额度

● 点击弹窗中的"Confirm & Unlock”使用该用户 1 次 unlock，扣减成功后，前往区域详情（报告）页，相关区域详情（报告）数据更新逻辑不变。

○ 扣减次数需要按照次数有效期进行判断，先过期的先使用

○ 过期时间一致的，按照🆔固定顺序解锁

● 用户首次通过扣减额度前往区域详情（报告）页，在页面toast提示；后续再次进入或者点击关闭都不再展示。

○ 点击 My Areas 可进入对应的页面

■ x 为账户剩余可用于解锁的次数

● 若 AI 还在生成中，已有的 AI 生成成功提示toast 成功优先级低于购买成功/解锁成功

四、  My Areas

1.Unlocked

1.  界面交互

2.  用户故事 (User Story)

● 作为一个已付费用户，我想要查看并管理所有已解锁的区域区域详情（报告），以便快速获取最新的房产市场见解并在区域详情（报告）过期前及时处理。

3.  功能点描述

● 右上角 recent 移除，换成新增页面”My Areas“

● 点击右上角菜单“My Areas"，点击进入 My Areas页

● 页面数据：所有 解锁过的区域详情（报告）和收藏过的区域详情（报告），不包括进入支付但是未支付购买的区域详情（报告）

○ 若区域详情（报告）先进行了购买，后续产生了退款，则区域详情（报告）在列表中展示，但不再展示查看按钮，仅做记录，此情况会在卡片字段说明中进行补充说明

○ 同一个邮编区域详情（报告），因为购买/退款或购买有更新的，在同一个数据上更新状态/信息

● 排序：可访问状态优先不可访问状态，同一状态根据购买/解锁时间倒序展示，即最新解锁的在前面

○ 若解锁后过期后再解锁，依然为同一条数据，但是同步更新解锁时间排签名

● 区域详情（报告）状态说明：

○ Active正常状态：区域详情（报告）还在有效期内，页面上不展示该状态标签

○ 区域详情（报告）已过更新有效期：当前时间晚于所购买区域详情（报告）的有效更新时间

○  AI 分析生成中：区域详情（报告）里的 AI 分析内容还未生成

○  AI 生成失败

○  区域详情（报告）被撤回：因为用户退款后，对区域详情（报告）进行了撤回，用户不可继续查看该区域详情（报告）

● 列表字段说明

4.  异常&分支流程

● 因为退款而退回的区域详情（报告），查看按钮置灰（最终以 UI稿为准 ）

● 若因为退款而退回的区域详情（报告），后续又进行了购买，则同一个邮编更新状态为最新状态

● 数据加载状态：页面初始化或翻页加载数据时，不使用全屏 Loading，而是在列表区域展示 10 个卡片的骨架屏动画

● 空数据（无区域详情（报告））状态：

○ 下面的搜索框，点击搜索以及搜索逻辑同首页一致

2.Saved

● 1. 用户故事 (User Story)

○ 作为一个潜在买家或投资者，我想要将感兴趣的区域收藏起来，以便在对比研究后决定消耗点数解锁哪些区域。

● 2. 业务流程/逻辑 (Business Process / Logic)

○ 用户搜索区域 -> 点击心型图标 -> 进入 Saved 列表 -> 选择 Unlock full area insights -> 校验 Credit -> 解锁成功 -> 移动至 Unlocked 列表。

● 3. 详细规格：页面、交互与规则

○ 页面与交互：

■ 心型收藏图标：点击可取消保存，卡片从列表中移除。

● 点击后出现提示，提示 5s 后消失

○ 点击提示中的 Undo 可以撤销“取消收藏”

■ 点击标题或空白区域卡片

● 已解锁的等同于点击“view Area Insights”

● 未解锁的点击后前往快照页

■ 列表字段参考 Unlocked

■ 操作按钮：

● 已解锁：同 unlocked 一致

● 未解锁：点击后进入对应的解锁/购买流程，判断逻辑跟快照页一致

○ 空数据状态

统一规则与逻辑 (Global Rules & Logic)

● 搜索说明：

○ 实时搜索：监听输入框的 input 或 keyup 事件

○ 搜索规则：当输入框为空时：显示所有卡片（根据分页规则）。当输入框有值时，根据邮编 postcode进行实时查询，设置 300ms 的防抖时间

○ 匹配逻辑： 不区分大小写 ，模糊匹配 (Partial Match) 邮编字段。

○ 根据搜索结果重新计算页数，对搜索词进行高亮展示

○ 清除搜索：当输入框有内容时，右侧出现 "X" 图标，点击可一键清空并恢复完整列表。

○ 搜索无结果提示：

● 2. 全局交互约定：

○ 标签切换： Unlocked 和 Saved 标签右侧应显示数字（如 Unlocked 3, Saved 2）

○ 响应式设计： 考虑到房地产经纪人可能在户外使用，卡片布局在移动端应自动切换为单行堆叠显示。

○ 加载状态： 切换标签页或执行解锁操作时，卡片应显示骨架屏（Skeleton Screen）以减少焦虑。

五、  Order History

5.1订单列表页

1.  界面交互

2.  功能点描述

● 点击用户头像，出现的下拉弹窗中，增加“Transactions”菜单，点击进入订单页

● 次数余额说明

○ 展示当前账户剩余的解锁次数

○ next expiry 当然展示为固定文案：

○ 点击“Top up unlocks”进入如 pricing 产品价格页

● 页面数据：所有完成支付的订单/解锁 unlock

○ 分为支付订单 Payments only和解锁订单Unlocks only

■ Payments：有支付金额的订单，也就是通过 stripe 支付的订单类、

● 不包括未支付成功的订单，包括支付成功后申请退款的订单

■  Unlocks：通过次数解锁的订单，无实际支付金额

●  Unlocks 包括因为过期扣除的次数

● 排序：根据购买/解锁时间倒序展示

● 数据加载：默认 10 条/次分页加载

● 订单状态说明：

○ Paid：已支付，正常状态

○ Refunded：用户申请了退款，并且处理退款完成

○ Processing Refund：用户申请了退款，退款正在处理中

○ Refund Declined：用户申请了退款，但是退款申请被拒绝

● 列表字段说明

3.  异常&分支流程

● 数据加载状态：页面初始化或翻页加载数据时，不使用全屏 Loading，而是在列表区域展示 10 个订单的骨架屏动画

● 空数据（无区域详情（报告））状态：

5.1订单详情弹窗

全局规则与逻辑 (Global Rules & Logic)

1. 格式化规范：

○ 货币显示： 英镑符号前置 (£1.99)，保留两位小数。若金额为0，显示 £0.00 或 £0（视具体场景）。

○ 次数显示： 使用特定单位词（如 1 unlock），不加货币符号。

○ 日期时间： 统一采用截图中的英式格式 DD Mon YYYY at HH:mm (例如：20 Sept 2024 at 09:15)。

2. 数据加载与空状态：

○ 点击列表项时，详情侧边栏/弹窗应从右侧滑入或在当前层级浮现。

○ 加载过程中，详情区域显示骨架屏（Skeleton Screen），保持布局稳定性。

3. 状态定义 (Order Status)：同列表一致

● 可以用于展示订单相关的信息

● 模态抽屉 (Modal Drawer)， 按 ESC 键、或（右上角的 × 关闭按钮可关闭弹窗

4.字段说明👇

5.3退款

1.  退款流程

2.  功能点描述

● 当前版本退款通过人工手动在 stripe后台发起，退次数通过 RR 手动操作

● 需要在退款成功后在订单中同步已退款状态到订单状态，并且对退款的订单撤回区域详情（报告）访问权，包括购买的次数

● 同样，若用户为通过 unlock 解锁，需要我们操作退款，并在页面展示退款状态

● 手动操作需要能：

1、把 stripe 的退款信息同步到订单中并把扣除的次数同步出来

默认扣除订单剩余未使用次数即可

2、把 unlock取消的状态同步到订单中

六、  Area Insights Page区域详情页

● 移除页面右上角 Analysis Date，替换为 最后更新时间Last update: 15/01/2024

● 时间展示为最近一次更新时间，展示格式跟报告时间一致

报告异常情况处理：

邮编详情页的URL调整后，若用户进入区域详情链接，需要校验用户是否具有访问权（包括过期的情况），若不具有，则自动触发并打开当前邮编的快照展示，并 toast 提示原因

首次访问平台：

访问过平台，但未购买当前区域访问权：

购买当前区域的访问权限已过期：

将现有的“快照页”内容作为该报告页的“默认展示层”，仅通过快照页或者 My areas 指定页面进入详情页

七、  Search

搜索历史管理 (Search History Management) - 新增核心]

1. 用户故事 (User Story)

○ 作为一个频繁对比不同区域的用户，我想要快速访问之前搜索过的位置，以便于节省重复输入的时间并追踪我的研究进度。

2. 业务流程/逻辑 (Business Process / Logic)

○ 记录产生： 用户点击建议列表中的某一项并成功跳转快照页后，该位置被计入“搜索历史”。

○ 展示逻辑： 当用户点击（Focus）空的输入框时，在下方以时间倒序展示最近的搜索项。

○ 删除逻辑： 用户点击单条历史后的删除图标 -> 实时移除该记录。

3. 详细规格：页面、交互与规则 (Detailed Specs: UI, Interactions & Rules)

○ 页面与交互：

■ [历史项图标]： 每条历史记录左侧配有“时钟/逆时针箭头”图标（如图中所示），以区分实时建议。

■ [删除触发]： 历史项最右侧设有 (X) 按钮。悬停（Hover）时高亮，点击即删除。

■ [区分显示]： 如果有输入的话，则改为展示搜索结果，若有与搜索记录匹配的邮编，则置顶展示。

■ 文案修改：Get your first full area area insights — Free，去掉后面的“— Free”

○ 规则与异常：

■ 规则 1（存储量）： [假设] 前端 LocalStorage 或后端数据库仅保留最近 10 条搜索历史。

■ 规则 2（去重）： 重复搜索同一地点时，该地点在历史列表中移动至最顶部，不产生重复条目。

■ 规则 3（登录同步）： [假设] 未登录状态下记录保存在浏览器缓存；登录后应同步至账号维度，实现多端一致。